
<!DOCTYPE html>
<html lang="en">
    <head>
        <title>Directives - vue.js</title>
        <meta charset="utf-8">
        <meta name="description" content="Vue.js - Intuitive, Fast and Composable MVVM for building interactive interfaces.">
        <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no">
        <link href='http://fonts.googleapis.com/css?family=Source+Sans+Pro:400,600|Source+Code+Pro|Dosis:300,500' rel='stylesheet' type='text/css'>
        <link rel="icon" href="/images/logo.png" type="image/x-icon">
        <script>
            window.PAGE_TYPE = "api"
        </script>
        <link rel="stylesheet" href="/css/page.css" type="text/css">
        <script>
  (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
  (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
  m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
  })(window,document,'script','//www.google-analytics.com/analytics.js','ga');

  ga('create', 'UA-46852172-1', 'vuejs.org');
  ga('send', 'pageview');
</script>
        <script src="/js/vue.js"></script>
    </head>
    <body>
        <div id="mobile-bar">
            <a class="menu-button"></a>
            <a class="logo" href="/"></a>
        </div>
        
            <div id="header">
    <a id="logo" href="/">
        <img src="/images/logo.png">
        <span>Vue.js</span>
    </a>
    <ul id="nav">
        <li>
  <form id="search-form">
    <input type="text" id="search-query" class="st-default-search-input">
  </form>
</li>
<li><a href="/guide/" class="nav-link">Guide</a></li>
<li><a href="/api/" class="nav-link current">API Reference</a></li>
<li><a href="/examples/" class="nav-link">Examples</a></li>
<li><a href="/blog/" class="nav-link">Blog</a></li>
<li><a href="https://github.com/yyx990803/vue" target="_blank" class="nav-link">GitHub</a></li>

    </ul>
</div>
            <div id="main">
                
                    
    <div class="sidebar">
    <ul class="main-menu">
        <li>
  <form id="search-form">
    <input type="text" id="search-query" class="st-default-search-input">
  </form>
</li>
<li><a href="/guide/" class="nav-link">Guide</a></li>
<li><a href="/api/" class="nav-link current">API Reference</a></li>
<li><a href="/examples/" class="nav-link">Examples</a></li>
<li><a href="/blog/" class="nav-link">Blog</a></li>
<li><a href="https://github.com/yyx990803/vue" target="_blank" class="nav-link">GitHub</a></li>

    </ul>
    <div class="list">
        <h2>Api</h2>
        <ul class="menu-root">
            
                <li>
                    <a href="/api/index.html" class="sidebar-link">Overview</a>
                </li>
            
                <li>
                    <a href="/api/options.html" class="sidebar-link">Component Options</a>
                </li>
            
                <li>
                    <a href="/api/instance-properties.html" class="sidebar-link">Instance Properties</a>
                </li>
            
                <li>
                    <a href="/api/instance-methods.html" class="sidebar-link">Instance Methods</a>
                </li>
            
                <li>
                    <a href="/api/global-api.html" class="sidebar-link">Global API</a>
                </li>
            
                <li>
                    <a href="/api/directives.html" class="sidebar-link current">Directives</a>
                </li>
            
                <li>
                    <a href="/api/filters.html" class="sidebar-link">Filters</a>
                </li>
            
                <li>
                    <a href="/api/elements.html" class="sidebar-link new">Special Elements</a>
                </li>
            
            <li><a href="http://legacy.vuejs.org">Looking for 0.11 docs?</a></li>
            <li style="margin:10px 0 3px">
              <script data-gittip-username="yyx990803"
                data-gittip-widget="button"
                src="//gttp.co/v1.js"></script>
            </li>
        </ul>
    </div>
</div>


<div class="content api with-sidebar">
    <h1>Directives</h1>
    <div id="ad">
        <script async type="text/javascript" src="//cdn.carbonads.com/carbon.js?zoneid=1673&serve=C6AILKT&placement=vuejs" id="_carbonads_js"></script>
    </div>
    <h2 id="Reactive_Directives">Reactive Directives</h2><blockquote>
<p>These directives can bind themselves to a property on the Vue instance, or to an expression which is evaluated in the context of the instance. When the value of the underlying property or expression changes, the <code>update()</code> function of these directives will be called asynchronously on next tick.</p>
</blockquote>
<h3 id="v-text">v-text</h3><p>Updates the element’s <code>textContent</code>.</p>
<p>Internally, &#123;&#123; Mustache &#125;&#125; interpolations are also compiled as a <code>v-text</code> directive on a textNode.</p>
<h3 id="v-html">v-html</h3><p>Updates the element’s <code>innerHTML</code>.</p>
<p class="tip">Using <code>v-html</code> with user-supplied data can be dangerous. It is suggested that you only use <code>v-html</code> when you are absolutely sure about the security of the data source, or pipe it through a custom filter that sanitizes untrusted HTML.</p>

<h3 id="v-show">v-show</h3><ul>
<li>This directive can trigger transitions.</li>
</ul>
<p>Set the element’s display to <code>none</code> or its original value, depending on the truthy-ness of the binding’s value.</p>
<h3 id="v-class">v-class</h3><ul>
<li>This directive accepts an optional argument.</li>
</ul>
<p>If no argument is provided, it will add the binding’s value to the element’s classList, and update the class as the value changes.</p>
<p>If a directive argument is provided, the argument will be the class to be toggled depending on the binding value’s truthy-ness. Combined with multiple clauses this can be pretty useful:</p>
<figure class="highlight html"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br></pre></td><td class="code"><pre><span class="line"><span class="tag">&lt;<span class="title">span</span> <span class="attribute">v-class</span>=<span class="value">"</span><br><span class="line">  red    : hasError,</span><br><span class="line">  bold   : isImportant,</span><br><span class="line">  hidden : isHidden</span><br><span class="line">"</span>&gt;</span><span class="tag">&lt;/<span class="title">span</span>&gt;</span></span><br></pre></td></tr></table></figure>
<p>Alternatively, you can bind the directive directly to an Object. The keys of the object will be the list of classes to toggle based on corresponding values.</p>
<h3 id="v-attr">v-attr</h3><ul>
<li>This directive requires an argument.</li>
</ul>
<p>Updates the element’s given attribute (indicated by the argument).</p>
<p><strong>Example:</strong></p>
<figure class="highlight html"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line"><span class="tag">&lt;<span class="title">canvas</span> <span class="attribute">v-attr</span>=<span class="value">"width:w, height:h"</span>&gt;</span><span class="tag">&lt;/<span class="title">canvas</span>&gt;</span></span><br></pre></td></tr></table></figure>
<p>Falsy values except 0 will remove the attribute.</p>
<p>Alternatively, you can bind the directive directly to an Object. The keys of the object will be the list of attributes to set based on corresponding values.</p>
<p>Internally, &#123;&#123; Mustache &#125;&#125; interpolations inside attributes are compiled into computed <code>v-attr</code> directives.</p>
<p>Starting in 0.12.9, when used on input elements’ <code>value</code> attribute, <code>v-attr</code> now updates the corresponding <code>value</code> property on the element instead of the attribute. For example, <code>&lt;input value=&quot;{{val}}&quot;&gt;</code> will update the underlying JavaScript property instead of the attribute.</p>
<p class="tip">You should use <code>v-attr</code> instead of mustache binding when setting the <code>src</code> attribute on <code>&lt;img&gt;</code> elements. Your templates are parsed by the browser before being compiled by Vue.js, so the mustache binding will cause a 404 when the browser tries to fetch it as the image’s URL.</p>

<h3 id="v-style">v-style</h3><ul>
<li>This directive accepts an optional argument.</li>
</ul>
<p>Apply inline CSS styles to the element.</p>
<p>When there is no argument, the bound value can either be a String or an Object.</p>
<ul>
<li>If it’s a String, it will be set as the element’s <code>style.cssText</code>.</li>
<li>If it’s an Object, each key/value pair will be set on the element’s <code>style</code> object.</li>
</ul>
<p><strong>Example:</strong></p>
<figure class="highlight html"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line"><span class="tag">&lt;<span class="title">div</span> <span class="attribute">v-style</span>=<span class="value">"myStyles"</span>&gt;</span><span class="tag">&lt;/<span class="title">div</span>&gt;</span></span><br></pre></td></tr></table></figure>
<figure class="highlight js"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br></pre></td><td class="code"><pre><span class="line"><span class="comment">// myStyles can either be a String:</span></span><br><span class="line"><span class="string">"color:red; font-weight:bold;"</span></span><br><span class="line"><span class="comment">// or an Object:</span></span><br><span class="line">&#123;</span><br><span class="line">  color: <span class="string">'red'</span>,</span><br><span class="line">  <span class="comment">// both camelCase and dash-case works</span></span><br><span class="line">  fontWeight: <span class="string">'bold'</span>,</span><br><span class="line">  <span class="string">'font-size'</span>: <span class="string">'2em'</span></span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure>
<p>When there is an argument, it will be used as the CSS property to apply. Combined with multiple clauses you can set multiple properties together:</p>
<p><strong>Example:</strong></p>
<figure class="highlight html"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br></pre></td><td class="code"><pre><span class="line"><span class="tag">&lt;<span class="title">div</span> <span class="attribute">v-style</span>=<span class="value">"</span><br><span class="line">  top: top + 'px',</span><br><span class="line">  left: left + 'px',</span><br><span class="line">  background-color: 'rgb(0,0,' + bg + ')'</span><br><span class="line">"</span>&gt;</span><span class="tag">&lt;/<span class="title">div</span>&gt;</span></span><br></pre></td></tr></table></figure>
<p><code>v-style</code> is also smart to detect any required browser vendor prefixes, so you can just use the un-prefixed version:</p>
<figure class="highlight html"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br></pre></td><td class="code"><pre><span class="line"><span class="comment">&lt;!-- will use -webkit-transform if needed, for example --&gt;</span></span><br><span class="line"><span class="tag">&lt;<span class="title">div</span> <span class="attribute">v-style</span>=<span class="value">"transform: 'scale(' + scale + ')'"</span>&gt;</span><span class="tag">&lt;/<span class="title">div</span>&gt;</span></span><br></pre></td></tr></table></figure>
<p class="tip">It is recommended to use <code>v-style</code> instead of mustache bindings inside <code>style</code> attribute because Internet Explorer, regardless of version, will remove invalid inline styles when parsing the HTML.</p>

<h3 id="v-on">v-on</h3><ul>
<li>This directive requires an argument.</li>
<li>This directive requires the value to be a Function or a statement.</li>
</ul>
<p>Attaches an event listener to the element. The event type is denoted by the argument. It is also the only directive that can be used with the <code>key</code> filter. For more details see <a href="/guide/events.html">Listening for Events</a>.</p>
<h3 id="v-model">v-model</h3><ul>
<li>This directive can only be used on <code>&lt;input&gt;</code>, <code>&lt;select&gt;</code> or <code>&lt;textarea&gt;</code> elements.</li>
<li>Directive params: <a href="/guide/forms.html#Lazy_Updates"><code>lazy</code></a>, <a href="/guide/forms.html#Casting_Value_as_Number"><code>number</code></a>, <a href="/guide/forms.html#Dynamic_Select_Options"><code>options</code></a>, <a href="/guide/forms.html#Input_Debounce"><code>debounce</code></a></li>
</ul>
<p>Create a two-way binding on a form input element. Data is synced on every <code>input</code> event by default. For detailed examples see <a href="/guide/forms.html">Handling Forms</a>.</p>
<h3 id="v-if">v-if</h3><ul>
<li>This directive can trigger transitions.</li>
</ul>
<p>Conditionally insert / remove the element based on the truthy-ness of the binding value. If the element is a <code>&lt;template&gt;</code> element, its content will be extracted as the conditional block.</p>
<p><strong>Example:</strong></p>
<figure class="highlight html"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br></pre></td><td class="code"><pre><span class="line"><span class="tag">&lt;<span class="title">template</span> <span class="attribute">v-if</span>=<span class="value">"test"</span>&gt;</span></span><br><span class="line">  <span class="tag">&lt;<span class="title">p</span>&gt;</span>hello<span class="tag">&lt;/<span class="title">p</span>&gt;</span></span><br><span class="line">  <span class="tag">&lt;<span class="title">p</span>&gt;</span>world<span class="tag">&lt;/<span class="title">p</span>&gt;</span></span><br><span class="line"><span class="tag">&lt;/<span class="title">template</span>&gt;</span></span><br></pre></td></tr></table></figure>
<p>Will render:</p>
<figure class="highlight html"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br></pre></td><td class="code"><pre><span class="line"><span class="comment">&lt;!--v-if-start--&gt;</span></span><br><span class="line"><span class="tag">&lt;<span class="title">p</span>&gt;</span>hello<span class="tag">&lt;/<span class="title">p</span>&gt;</span></span><br><span class="line"><span class="tag">&lt;<span class="title">p</span>&gt;</span>world<span class="tag">&lt;/<span class="title">p</span>&gt;</span></span><br><span class="line"><span class="comment">&lt;!--v-if-end--&gt;</span></span><br></pre></td></tr></table></figure>
<h3 id="v-repeat">v-repeat</h3><ul>
<li>This directive creates child Vue instances.</li>
<li>This directive requires the value to be an Array, Object or Number.</li>
<li>This directive can trigger transitions.</li>
<li>This directive accepts an optional argument.</li>
<li>Directive params: <a href="/guide/list.html#Using_track-by"><code>track-by</code></a>, <a href="/guide/transitions.html#Staggering_Transitions"><code>stagger</code></a>, <a href="/guide/transitions.html#Staggering_Transitions"><code>enter-stagger</code></a>, <a href="/guide/transitions.html#Staggering_Transitions"><code>leave-stagger</code></a></li>
</ul>
<p>Create a child ViewModel for every item in the binding Array or Object. If the value is a whole Number then that many child ViewModels are created. These child ViewModels will be automatically created / destroyed when mutating methods, e.g. <code>push()</code>, are called on the Array or Object, or the number is increased or decreased.</p>
<p>When no argument is provided, the child ViewModel will directly use the assigned element in the Array as its <code>$data</code>. If the value is not an object, a wrapper data object will be created and the value will be set on that object using the alias key <code>$value</code>.</p>
<p><strong>Example:</strong></p>
<figure class="highlight html"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br></pre></td><td class="code"><pre><span class="line"><span class="tag">&lt;<span class="title">ul</span>&gt;</span></span><br><span class="line">  <span class="tag">&lt;<span class="title">li</span> <span class="attribute">v-repeat</span>=<span class="value">"users"</span>&gt;</span></span><br><span class="line">    &#123;&#123;name&#125;&#125; &#123;&#123;email&#125;&#125;</span><br><span class="line">  <span class="tag">&lt;/<span class="title">li</span>&gt;</span></span><br><span class="line"><span class="tag">&lt;/<span class="title">ul</span>&gt;</span></span><br></pre></td></tr></table></figure>
<p>If an argument is provided, a wrapper data object will always be created, using the argument string as the alias key. This allows for more explicit property access in templates:</p>
<figure class="highlight html"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br></pre></td><td class="code"><pre><span class="line"><span class="tag">&lt;<span class="title">ul</span>&gt;</span></span><br><span class="line">  <span class="tag">&lt;<span class="title">li</span> <span class="attribute">v-repeat</span>=<span class="value">"user : users"</span>&gt;</span></span><br><span class="line">    &#123;&#123;user.name&#125;&#125; &#123;&#123;user.email&#125;&#125;</span><br><span class="line">  <span class="tag">&lt;/<span class="title">li</span>&gt;</span></span><br><span class="line"><span class="tag">&lt;/<span class="title">ul</span>&gt;</span></span><br></pre></td></tr></table></figure>
<p>Starting in 0.12.8, a special alternative is available to make the syntax more natural:</p>
<figure class="highlight html"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br></pre></td><td class="code"><pre><span class="line"><span class="tag">&lt;<span class="title">ul</span>&gt;</span></span><br><span class="line">  <span class="tag">&lt;<span class="title">li</span> <span class="attribute">v-repeat</span>=<span class="value">"user in users"</span>&gt;</span></span><br><span class="line">    &#123;&#123;user.name&#125;&#125; &#123;&#123;user.email&#125;&#125;</span><br><span class="line">  <span class="tag">&lt;/<span class="title">li</span>&gt;</span></span><br><span class="line"><span class="tag">&lt;/<span class="title">ul</span>&gt;</span></span><br></pre></td></tr></table></figure>
<p>For detailed examples, see <a href="/guide/list.html">Displaying a List</a>.</p>
<h2 id="Literal_Directives">Literal Directives</h2><blockquote>
<p>Literal directives treat their attribute value as a plain string; they do not attempt to bind themselves to anything. All they do is executing the <code>bind()</code> function once. Literal directives can also accept mustache expressions inside their value - please refer to <a href="/guide/custom-directive.html#Dynamic_Literal">Dynamic Literal</a> for more details.</p>
</blockquote>
<h3 id="v-transition">v-transition</h3><ul>
<li>Can be made reactive with mustaches</li>
</ul>
<p>Notify Vue.js to apply transitions to this element. The transition classes are applied when certain transition-triggering directives modify the element, or when the Vue instance’s DOM manipulation methods are called.</p>
<p>For details, see <a href="/guide/transitions.html">the guide on transitions</a>.</p>
<h3 id="v-ref">v-ref</h3><p>Register a reference to a child component on its parent for easier access. Only respected when used on a component or with <code>v-repeat</code>. The component instance will be accessible on its parent’s <code>$</code> object. For an example, see <a href="/guide/components.html#Child_Reference">child reference</a>.</p>
<p>When used with <code>v-repeat</code>, the value will be an Array containing all the child Vue instances corresponding to the Array they are bound to.</p>
<p>New in 0.12: If the <code>v-repeat</code>‘s source data is an Object, then <code>v-ref</code> will return an Object with instances matching each key in the Object.</p>
<h3 id="v-el">v-el</h3><p>Register a reference to a DOM element on its owner Vue instance for easier access. e.g. <code>&lt;div v-el=&quot;hi&quot;&gt;</code> will be accessible as <code>vm.$$.hi</code>.</p>
<h2 id="Empty_Directives">Empty Directives</h2><blockquote>
<p>Empty directives do not require and will ignore their attribute value.</p>
</blockquote>
<h3 id="v-pre">v-pre</h3><p>Skip compilation for this element and all its children. Skipping large numbers of nodes with no directives on them can speed up compilation.</p>
<h3 id="v-cloak">v-cloak</h3><p>This property remains on the element until the associated ViewModel finishes compilation. Combined with CSS rules such as <code>[v-cloak] { display: none }</code>, this directive can be used to hide un-compiled mustache bindings until the ViewModel is ready.</p>

    <div class="footer">Caught a mistake or want to contribute to the documentation? <a href="https://github.com/vuejs/vuejs.org" target="_blank">Fork this site on Github</a>!</div>
</div>
                
            </div>
            <script src="/js/smooth-scroll.min.js"></script>
            <script src="/js/common.js"></script>
        

        <script src="https://cdnjs.cloudflare.com/ajax/libs/fastclick/1.0.6/fastclick.min.js"></script><script src="https://cdn.jsdelivr.net/gh/shentao/vuejs-outdated-docs-modal@v1.3/prompt.min.js"></script>
        <script>
            document.addEventListener('DOMContentLoaded', function() {
                FastClick.attach(document.body);
            }, false);
        </script>
    </body>
</html>
